Module Architecture

flowchart TD
    SUB["sadeem_subscription\nSubscription Base"]
    PORT["sadeem_portainer\nPortainer"]
    CF["sadeem_cloudflare\nCloudflare"]

    S["sadeem.subscription (inherit)\nDocker type · image · ports\nstack compose generation"]
    ST["sadeem.subscription.stage (inherit)\nper-stage Docker stack\ndatabase · volumes · ports"]
    ENV["sadeem.portainer.environment (inherit)\nsubscription count per environment"]
    IMGTAG["sadeem.portainer.image.tag (inherit)\nDocker image version tags"]
    UPD["sadeem.subscription.update.request (inherit)\nDocker-specific resource upgrade"]

    SUB --> S
    PORT --> S
    CF --> S

    S --> ST
    S --> ENV
    S --> UPD

    ST --> SK1([action_portainer_create_stack\ngenerate compose → deploy via Portainer])
    ST --> SK2([action_docker_stack_update\nredeploy stack with new config])
    ST --> SK3([action_restart_docker\nrestart container])
    ST --> SK4([action_docker_log\nstream container logs])
    ST --> SK5([action_docker_run_cmd\nexec command in container])
    ST --> SK6([action_docker_cp_subscription_addons\ncopy addons into running stack])
    ST --> SK7([action_cancel_docker\nstop and remove Docker stack])

    S --> CS1([action_create_code_server\ndeploy VS Code container])
    S --> CS2([action_start_code_server\nstart VS Code container])
    S --> CS3([action_stop_code_server\nstop VS Code container])
    S --> CS4([action_remove_code_server\nremove VS Code container])

    S --> PM1([action_confirm override\nauto-assign HTTP + WebSocket ports])
    IMGTAG --> PM2([get_best_environment\npick Docker host by capacity])

    EXT[/Portainer API\nstack and container CRUD/]
    SK1 --> EXT
    SK2 --> EXT
    SK4 --> EXT
    SK5 --> EXT

Module Description

Adds the Docker deployment strategy to the Sadeem SAAS platform. Each subscription is deployed as an isolated Docker stack via Portainer with its own Odoo instance and database.

Dependencies

• sadeem_cloudflare
• sadeem_subscription
• product
• sadeem_portainer

Menus

This module does not add new menu items. It extends the subscription and stage forms with Docker-specific tabs and actions.

Subscription Type

This module adds the docker selection value to saas_subscription_type. When selected, subscriptions are provisioned as isolated Docker stacks managed through Portainer.

Key Fields

Subscription — Docker additions (sadeem.subscription inherit)

Stage — Docker additions (sadeem.subscription.stage inherit)

Lifecycle & States

The Docker module uses the same subscription and stage states defined in sadeem_subscription. Key Docker-specific behaviors:

• Port assignment at confirm: action_confirm override auto-assigns http_port and websocket_port by calling get_best_environment() on the image; raises UserError if no environment is available.
• Stack creation: action_portainer_create_stack builds the Docker Compose string and deploys via Portainer API; both subscription and stage have this action.
• Stack redeployment: action_docker_stack_update regenerates the compose and updates the running stack.
• Cancellation: action_cancel stops and removes the Portainer stack before marking the subscription/stage cancelled.

Key Actions

Warnings & Important Notes

• HTTP port required: action_run_subscription raises UserError if http_port is 0 — happens if the subscription was not confirmed properly. Reset to draft and confirm again.
• No environment available: action_confirm raises UserError if docker_image has no available/configured environment.
• Log tail limit: Fetching more than 1000 lines raises UserError.
• Command safety check: action_docker_run_cmd passes commands through is_safe_command() in sadeem_saas_docker/utils/utils.py; raises UserError for disallowed commands.
• Stack creation failure: action_portainer_create_stack raises ValidationError with the Portainer error message on failure.
• Code server stack: The VS Code container is deployed as a separate Portainer stack; code_server_stack_id tracks it independently from stack_id.